Точни типове в TypeScript: Стриктно съответствие на формата на обекти за по-здрав код

TypeScript, надмножество на JavaScript, въвежда статично типизиране в динамичния свят на уеб разработката. Въпреки че TypeScript предлага значителни предимства по отношение на типовата безопасност и поддръжката на кода, неговата система за структурно типизиране понякога може да доведе до неочаквано поведение. Тук се появява концепцията за „точни типове“. Макар TypeScript да няма вградена функция, изрично наречена „точни типове“, можем да постигнем подобно поведение чрез комбинация от функции и техники на TypeScript. Тази блог публикация ще разгледа как да наложим по-стриктно съответствие на формата на обектите в TypeScript, за да подобрим здравината на кода и да предотвратим често срещани грешки.

Разбиране на структурното типизиране в TypeScript

TypeScript използва структурно типизиране (известно още като duck typing), което означава, че съвместимостта на типовете се определя от членовете на типовете, а не от техните декларирани имена. Ако един обект има всички свойства, изисквани от даден тип, той се счита за съвместим с този тип, независимо дали има допълнителни свойства.

Например:

interface Point {
  x: number;
  y: number;
}

const myPoint = { x: 10, y: 20, z: 30 };

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}

printPoint(myPoint); // Това работи безпроблемно, въпреки че myPoint има свойство 'z'

В този сценарий TypeScript позволява `myPoint` да бъде подаден на `printPoint`, защото съдържа необходимите свойства `x` и `y`, въпреки че има и допълнително свойство `z`. Макар тази гъвкавост да е удобна, тя може да доведе до фини бъгове, ако неволно подадете обекти с неочаквани свойства.

Проблемът с излишните свойства

Свободата на структурното типизиране понякога може да прикрие грешки. Разгледайте функция, която очаква конфигурационен обект:

interface Config {
  apiUrl: string;
  timeout: number;
}

function setup(config: Config) {
  console.log(`API URL: ${config.apiUrl}`);
  console.log(`Timeout: ${config.timeout}`);
}

const myConfig = { apiUrl: "https://api.example.com", timeout: 5000, typo: true };

setup(myConfig); // TypeScript не се оплаква тук!

console.log(myConfig.typo); //извежда true. Допълнителното свойство съществува тихомълком

В този пример `myConfig` има допълнително свойство `typo`. TypeScript не предизвиква грешка, защото `myConfig` все още удовлетворява интерфейса `Config`. Правописната грешка обаче никога не се улавя и приложението може да не се държи според очакванията, ако грешката е трябвало да бъде `typoo`. Тези на пръв поглед незначителни проблеми могат да се превърнат в сериозни главоболия при дебъгване на сложни приложения. Липсващо или грешно изписано свойство може да бъде особено трудно за откриване, когато се работи с вложени обекти.

Подходи за налагане на точни типове в TypeScript

Въпреки че истински „точни типове“ не са директно налични в TypeScript, ето няколко техники за постигане на подобни резултати и налагане на по-стриктно съответствие на формата на обектите:

1. Използване на утвърждаване на тип (Type Assertions) с `Omit`

Помощният тип `Omit` ви позволява да създадете нов тип, като изключите определени свойства от съществуващ тип. В комбинация с утвърждаване на тип, това може да помогне за предотвратяване на излишни свойства.

interface Point {
  x: number;
  y: number;
}

const myPoint = { x: 10, y: 20, z: 30 };

// Създаване на тип, който включва само свойствата на Point
const exactPoint: Point = myPoint as Omit & Point;

// Грешка: Тип '{ x: number; y: number; z: number; }' не може да бъде присвоен на тип 'Point'.
// Обектният литерал може да указва само познати свойства, а 'z' не съществува в тип 'Point'.

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}


//Поправка
const myPointCorrect = { x: 10, y: 20 };
const exactPointCorrect: Point = myPointCorrect as Omit & Point;
printPoint(exactPointCorrect);

Този подход предизвиква грешка, ако `myPoint` има свойства, които не са дефинирани в интерфейса `Point`.

Обяснение: `Omit` създава тип, който пропуска всички ключове, присъстващи в `Point`, от типа на `myPoint`. След това `& Point` пресича този тип с типа `Point`, като по същество изисква обектът да съответства на типа `Point`. Чрез утвърждаването на обекта към този комбиниран тип, компилаторът проверява за допълнителни свойства и предизвиква грешка, ако намери такива. Това ни принуждава да декларираме правилната форма при първоначалното дефиниране на нашия обект.

2. Използване на функция за създаване на обекти

Можете да създадете фабрична функция (factory function), която приема само свойствата, дефинирани в интерфейса. Този подход осигурява силна проверка на типовете в момента на създаване на обекта.

interface Config {
  apiUrl: string;
  timeout: number;
}

function createConfig(config: Config): Config {
  return {
    apiUrl: config.apiUrl,
    timeout: config.timeout,
  };
}

const myConfig = createConfig({ apiUrl: "https://api.example.com", timeout: 5000 });

//Това няма да се компилира:
//const myConfigError = createConfig({ apiUrl: "https://api.example.com", timeout: 5000, typo: true });
//Аргумент от тип '{ apiUrl: string; timeout: number; typo: true; }' не може да бъде присвоен на параметър от тип 'Config'.
// Обектният литерал може да указва само познати свойства, а 'typo' не съществува в тип 'Config'.

Като връщате обект, конструиран само със свойствата, дефинирани в интерфейса `Config`, вие гарантирате, че не могат да се промъкнат допълнителни свойства. Това прави създаването на конфигурацията по-безопасно.

3. Използване на предпазители на типове (Type Guards)

Предпазителите на типове са функции, които стесняват типа на променлива в определен обхват. Въпреки че не предотвратяват директно излишните свойства, те могат да ви помогнат да ги проверите изрично и да предприемете съответните действия.

interface User {
  id: number;
  name: string;
}

function isUser(obj: any): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj && typeof obj.id === 'number' &&
    'name' in obj && typeof obj.name === 'string' &&
    Object.keys(obj).length === 2 //проверка за броя на ключовете. Забележка: това е чупливо и зависи от точния брой ключове на User.
  );
}

const potentialUser1 = { id: 123, name: "Alice" };
const potentialUser2 = { id: 456, name: "Bob", extra: true };

if (isUser(potentialUser1)) {
  console.log("Валиден потребител:", potentialUser1.name);
} else {
  console.log("Невалиден потребител");
}

if (isUser(potentialUser2)) {
  console.log("Валиден потребител:", potentialUser2.name); //Няма да влезе тук
} else {
  console.log("Невалиден потребител");
}

В този пример, предпазителят на тип `isUser` проверява не само за наличието на задължителни свойства, но и за техните типове и *точния* брой на свойствата. Този подход е по-изричен и ви позволява да обработвате невалидни обекти елегантно. Проверката за броя на свойствата обаче е крехка. Всеки път, когато `User` придобие/загуби свойства, проверката трябва да бъде актуализирана.

4. Използване на `Readonly` и `as const`

Докато `Readonly` предотвратява промяната на съществуващи свойства, а `as const` създава кортеж или обект само за четене, където всички свойства са дълбоко само за четене и имат литерални типове, те могат да се използват за създаване на по-стриктна дефиниция и проверка на типове, когато се комбинират с други методи. Въпреки това, нито едно от тях не предотвратява излишните свойства само по себе си.

interface Options {
  width: number;
  height: number;
}

//Създаване на тип Readonly
type ReadonlyOptions = Readonly;

const options: ReadonlyOptions = { width: 100, height: 200 };

//options.width = 300; //грешка: Не може да се присвои стойност на 'width', защото е свойство само за четене.

//Използване на as const
const config = { api_url: "https://example.com", timeout: 3000 } as const;

//config.timeout = 5000; //грешка: Не може да се присвои стойност на 'timeout', защото е свойство само за четене.

//Въпреки това, излишните свойства все още са разрешени:
const invalidOptions: ReadonlyOptions = { width: 100, height: 200, depth: 300 }; //няма грешка. Все още позволява излишни свойства.


interface StrictOptions {
  readonly width: number;
  readonly height: number;
}

//Сега това ще даде грешка:
//const invalidStrictOptions: StrictOptions = { width: 100, height: 200, depth: 300 };
//Тип '{ width: number; height: number; depth: number; }' не може да бъде присвоен на тип 'StrictOptions'.
//  Обектният литерал може да указва само познати свойства, а 'depth' не съществува в тип 'StrictOptions'.

Това подобрява неизменността, но предотвратява само мутацията, а не съществуването на допълнителни свойства. В комбинация с `Omit` или с функционалния подход, става по-ефективно.

5. Използване на библиотеки (напр. Zod, io-ts)

Библиотеки като Zod и io-ts предлагат мощни възможности за валидиране на типове по време на изпълнение и дефиниране на схеми. Тези библиотеки ви позволяват да дефинирате схеми, които точно описват очакваната форма на вашите данни, включително предотвратяване на излишни свойства. Въпреки че добавят зависимост по време на изпълнение, те предлагат много стабилно и гъвкаво решение.

Пример със Zod:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

type User = z.infer;

const validUser = { id: 1, name: "John" };
const invalidUser = { id: 2, name: "Jane", extra: true };

const parsedValidUser = UserSchema.parse(validUser);
console.log("Парснат валиден потребител:", parsedValidUser);

try {
  const parsedInvalidUser = UserSchema.parse(invalidUser);
  console.log("Парснат валиден потребител:", parsedInvalidUser); // Този код няма да бъде достигнат
} catch (error) {
  console.error("Грешка при валидация:", error.errors);
}

Методът `parse` на Zod ще хвърли грешка, ако входните данни не отговарят на схемата, като ефективно предотвратява излишните свойства. Това осигурява валидация по време на изпълнение и също така генерира TypeScript типове от схемата, гарантирайки последователност между вашите дефиниции на типове и логиката за валидация по време на изпълнение.

Добри практики за налагане на точни типове

Ето някои добри практики, които трябва да имате предвид при налагането на по-стриктно съответствие на формата на обекти в TypeScript:

• Изберете правилната техника: Най-добрият подход зависи от вашите специфични нужди и изисквания на проекта. За прости случаи, утвърждаванията на типове с `Omit` или фабричните функции може да са достатъчни. За по-сложни сценарии или когато се изисква валидация по време на изпълнение, обмислете използването на библиотеки като Zod или io-ts.
• Бъдете последователни: Прилагайте избрания от вас подход последователно в целия си код, за да поддържате равномерно ниво на типова безопасност.
• Документирайте типовете си: Ясно документирайте вашите интерфейси и типове, за да съобщите очакваната форма на данните на другите разработчици.
• Тествайте кода си: Пишете единични тестове (unit tests), за да проверите дали вашите типови ограничения работят според очакванията и дали кодът ви обработва невалидни данни елегантно.
• Обмислете компромисите: Налагането на по-стриктно съответствие на формата на обекти може да направи кода ви по-стабилен, но също така може да увеличи времето за разработка. Претеглете ползите спрямо разходите и изберете подхода, който е най-подходящ за вашия проект.
• Постепенно въвеждане: Ако работите по голяма съществуваща кодова база, обмислете да въвеждате тези техники постепенно, като започнете от най-критичните части на вашето приложение.
• Предпочитайте интерфейси пред псевдоними на типове (type aliases) при дефиниране на форми на обекти: Интерфейсите обикновено се предпочитат, защото поддържат сливане на декларации (declaration merging), което може да бъде полезно за разширяване на типове в различни файлове.

Примери от реалния свят

Нека разгледаме някои сценарии от реалния свят, в които точните типове могат да бъдат от полза:

• Данни за API заявки (payloads): Когато изпращате данни към API, е изключително важно да се уверите, че данните отговарят на очакваната схема. Налагането на точни типове може да предотврати грешки, причинени от изпращане на неочаквани свойства. Например, много API-та за обработка на плащания са изключително чувствителни към неочаквани данни.
• Конфигурационни файлове: Конфигурационните файлове често съдържат голям брой свойства и правописните грешки са често срещани. Използването на точни типове може да помогне за улавянето на тези грешки на ранен етап. Ако настройвате местоположения на сървъри в облачна среда, правописна грешка в настройката за местоположение (напр. eu-west-1 срещу eu-wet-1) ще стане изключително трудна за отстраняване, ако не бъде уловена предварително.
• Конвейери за трансформация на данни: При трансформиране на данни от един формат в друг е важно да се гарантира, че изходните данни отговарят на очакваната схема.
• Опашки за съобщения: Когато изпращате съобщения през опашка за съобщения, е важно да се уверите, че съдържанието на съобщението е валидно и съдържа правилните свойства.

Пример: Конфигурация за интернационализация (i18n)

Представете си, че управлявате преводи за многоезично приложение. Може да имате конфигурационен обект като този:

interface Translation {
  greeting: string;
  farewell: string;
}

interface I18nConfig {
  locale: string;
  translations: Translation;
}

const englishConfig: I18nConfig = {
  locale: "en-US",
  translations: {
    greeting: "Hello",
    farewell: "Goodbye"
  }
};


//Това ще бъде проблем, тъй като съществува излишно свойство, което тихомълком въвежда бъг.
const spanishConfig: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós",
    typo: "неумишлен превод"
  }
};

//Решение: Използване на Omit
const spanishConfigCorrect: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós"
  } as Omit & Translation
};

Без точни типове, правописна грешка в ключ за превод (като добавяне на поле `typo`) може да остане незабелязана, което да доведе до липсващи преводи в потребителския интерфейс. Чрез налагане на по-стриктно съответствие на формата на обекти, можете да уловите тези грешки по време на разработка и да предотвратите достигането им до продукция.

Заключение

Въпреки че TypeScript няма вградени „точни типове“, можете да постигнете подобни резултати, като използвате комбинация от функции и техники на TypeScript като утвърждаване на типове с `Omit`, фабрични функции, предпазители на типове, `Readonly`, `as const` и външни библиотеки като Zod и io-ts. Чрез налагане на по-стриктно съответствие на формата на обектите, можете да подобрите стабилността на кода си, да предотвратите често срещани грешки и да направите приложенията си по-надеждни. Не забравяйте да изберете подхода, който най-добре отговаря на вашите нужди, и да бъдете последователни в прилагането му в целия си код. Като обмислите внимателно тези подходи, можете да поемете по-голям контрол върху типовете на вашето приложение и да увеличите дългосрочната му поддръжка.